package com.naiterui.common.redis.template;

import java.util.Map;
import java.util.Set;

import com.naiterui.common.redis.annotation.Cautious;

/**
 * Redis ZSets Operation Template
 */
public interface IRedisZSetTemplate {

    // ++++++++++++++++++++++++++++++++ redis zset 操作 ++++++++++++++++++++++++++++++++ //

    /**
     * 将指定成员添加到键为key有序集合（sorted set）里面
     * 如果指定添加的成员已经是有序集合里面的成员，则会更新改成员的分数（score）并更新到正确的排序位置
     *
     * @param key
     * @param score
     * @param member
     *
     * @return
     */
    Long zadd(String key, double score, String member);

    /**
     * 类似zadd(String,double,String)
     *
     * @param key
     * @param scoreMembers
     *
     * @return
     */
    Long zadd(String key, Map<String, Double> scoreMembers);

    /**
     * 移除有序集key中，所有score值介于min和max之间(包括等于min或max)的成员
     *
     * @param key
     * @param min
     * @param max
     *
     * @return
     */
    @Cautious
    Long zremrangeByScore(String key, double min, double max);

    /**
     * 返回key的有序集合中的分数在min和max之间的所有元素（包括分数等于max或者min的元素）
     * 元素被认为是从低分到高分排序的，具有相同分数的元素按字典序排列
     * （这个根据redis对有序集合实现的默认排序而定，并不进一步计算）
     *
     * @param key
     * @param min
     * @param max
     *
     * @return
     */
    @Cautious
    Set<String> zrangeByScore(String key, double min, double max);

    /**
     * 类似zrangeByScore(String,double,double)
     * 返回key的有序集合中的分数在min和max之间的所有元素及其分数
     *
     * @param key
     * @param min
     * @param max
     *
     * @return
     */
    @Cautious
    Map<String, Double> zrangeByScoreWithScores(String key, double min, double max);

    /**
     * 返回有序集key中，指定区间内的成员
     * 其中成员的位置按score值递减(从小到大)来排列
     * 具有相同score值的成员按字典序排列
     *
     * @param key
     * @param start
     * @param stop
     *
     * @return
     */
    Set<String> zrange(String key, long start, long stop);

    /**
     * 返回有序集key中，指定区间内的成员及score
     * 其中成员的位置按score值递减(从小到大)来排列
     * 具有相同score值的成员按字典序排列
     *
     * @param key
     * @param start
     * @param stop
     *
     * @return
     */
    Map<String, Double> zrangeWithScore(String key, long start, long stop);

    /**
     * 类似zrange(String,long,long)
     * 其中成员的位置按score值递减(从大到小)来排列
     * 具有相同score值的成员按字典序的反序排列
     *
     * @param key
     * @param start
     * @param end
     *
     * @return
     */
    Set<String> zrevrange(String key, long start, long end);

    /**
     * 返回有序集key中，指定区间内的成员及score
     * 其中成员的位置按score值递减(从大到小)来排列
     * 具有相同score值的成员按字典序排列
     *
     * @param key
     * @param start
     * @param stop
     *
     * @return
     */
    Map<String, Double> zrevrangeWithScore(String key, long start, long stop);

    /**
     * 返回有序集key中，成员member的score值
     * 如果member元素不是有序集key的成员，或key不存在，返回null
     *
     * @param key
     * @param member
     *
     * @return
     */
    Double zscore(String key, String member);

    /**
     * 为有序集key的成员member的score值加上增量increment
     * 如果key中不存在member，就在key中添加一个member，score是increment（可以理解原score为0.0）
     * 如果key不存在，就创建一个只含有指定member成员的有序集合
     *
     * @param key
     * @param score
     * @param member
     *
     * @return
     */
    Double zincrby(String key, double score, String member);

    /**
     * 批量删除有序集合中member
     * 返回的是从有序集合中删除的成员个数（不包括不存在的member）
     * 当key存在，但是其不是有序集合类型，就返回null
     *
     * @param key
     * @param members
     *
     * @return
     */
    Long zrem(String key, String... members);

    /**
     * 移除有序集key中，指定排名(rank)区间内的所有成员
     * 支持正负，+：代表顺序索引，如1，代表分数从小到大，第一个；-1，代表分数从大到小第一个
     * 0则代表默认顺序索引，第一个元素，及分数最小的成员
     *
     * @param key
     * @param start
     * @param stop
     *
     * @return
     */
    @Cautious
    Long zremrangeByRank(String key, long start, long stop);

    /**
     * 返回key的有序集元素个数
     *
     * @param key
     *
     * @return
     */
    Long zcard(String key);
}
